home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / DEVELOP.ZIP / FILEIDX.DOC < prev    next >
Text File  |  1996-07-05  |  5KB  |  120 lines
  1. The following information describes the download path index files that are
  2. used by PCBoard.  Lines marked with a vertical bar (|) were added on 7/5/96
  3. in support of PCBoard v15.3's new style IDX file.
  4.  
  5. | NOTE:  Beginning with PCBoard v15.3, two IDX formats are supported by
  6. |        PCBoard.  Both formats are "similar", enough so that you can share
  7. |        most of the code in handling them.  The new format is mostly
  8. |        different in that it uses 4-byte long integers instead of the 2-byte
  9. |        short integers used in the old format. It also includes in the file
  10. |        record portion of the file a 4-byte long integer representing the
  11. |        size of the file.
  12. |
  13. |        The new style of index is created by running MAKEIDX with a /E
  14. |        command line parameter.  Most sysops will probably continue to use
  15. |        the old style index while reserving the new style index primarily
  16. |        for CD-ROMs.
  17.  
  18.  
  19.   File Specification
  20.   ==================
  21.  
  22.   Old Style IDX Header
  23.   --------------------
  24.    2 bytes for an integer indicating the number of files
  25.   52 bytes for 26 integers indicating starting points for A thru Z
  26. | 73 bytes reserved space
  27. |  1 byte as a "ID" value which is 0 to indicate the old style index
  28.  
  29.   typedef struct {
  30.     unsigned NumFiles;
  31.     unsigned RecOffset[26];
  32.     char     Reserved[73];        // set to all zeroes
  33.     char     Id;                  // set to 0 - indicates old style index
  34.   } idxhdrtype;
  35.  
  36. | New Style IDX Header
  37. | --------------------
  38. |   4 bytes for a long integer indicating the number of files
  39. | 104 bytes for 26 long integers indicating starting points for A thru Z
  40. |  19 bytes reserved space
  41. |  1 byte as a "ID" value which is 1 to indicate the NEW style index
  42. |
  43. | typedef struct {
  44. |   unsigned long NumFiles;
  45. |   unsigned long RecOffset[26];
  46. |   char          Reserved[19];   // set to all zeroes
  47. |   char          Id;             // set to 1 - indicates NEW style index
  48. | } newidxhdrtype;
  49.  
  50.  
  51.   Old Style File Name Records
  52.   ---------------------------
  53.   The filename records include:
  54.   -  11 bytes for a filename of the form:  nnnnnnnneee
  55.      any character not used is filled with a space
  56.   -  the path associated with the file is represented by a path number
  57.  
  58.   typedef struct {
  59.     char     Name[8];
  60.     char     Ext[3];
  61.     unsigned PathNum;
  62.   } nametype;
  63.  
  64.  
  65. | New Style File Name Records
  66. | ---------------------------
  67. | The new style record is the same as above with two differences:
  68. | -  The PathNum variable is a 4-byte long integer
  69. | -  In the new style index, a 4-byte long integer is included to indicate
  70. |    the size of the file
  71. |
  72. | typedef struct {
  73. |   char          Name[8];
  74. |   char          Ext[3];
  75. |   unsigned long PathNum;
  76. |   unsigned long FileSize;
  77. | } newnametype;
  78.  
  79.  
  80.   Path Records (the same in both IDX styles)
  81.   ==========================================
  82.   Paths are stored as fixed length records, each one is 64 bytes which includes
  83.   a NUL terminator at the end of the path:
  84.  
  85.   typedef struct {
  86.     char Path[64];
  87.   } pathtype;
  88.  
  89.  
  90.   File Layout and Accessing the File
  91.   ==================================
  92. | The first thing you need to do is read the header of the IDX file and look
  93. | at the byte at offset 127, which is the ID byte.  If it is 0, then use the
  94. | structure defined as idxhdrtype shown above.  If it is a 1, then use the
  95. | structure defined as newidxhdrtype.  The remainder of the "logic" for
  96. | accessing the files remains the same whether using the old or new style IDX
  97. | file.  Just remember to use the proper integer sizes (short in old style and
  98. | long in the new style).
  99.  
  100.   Following the header is the list of filenames which are then followed by
  101.   paths.
  102.  
  103.   The header consists of 26 separate values which indicate the record number
  104.   (offset 0) of the first filename starting with each of the letters A thru Z.
  105.   This reduces the number of file seeks performed by immediately narrowing down
  106.   the search records.  It also increases the likelyhood that all file seeks
  107.   will be performed within the memory buffer that is read in from disk.
  108.  
  109.   For instance, if the file to be found starts with the letter "B" then looking
  110.   at offset numbers for "B" and "C" (let's say they are record numbers 100 and
  111.   200 respectively out of 1000 files) we can narrow down the search to records
  112.   100-200 immediately without having to read files at the very end of the list.
  113.  
  114.   Files starting with letters before 'A' will be placed immediately following
  115.   the header so no offset value is recorded there.  Files that start with
  116.   letters after 'Z' will follow those filenames starting with 'Z'.
  117.  
  118.   A binary search is then used to locate the filename.  Note the format of
  119.   the filenames which makes it easy to use a wildcard matching technique.
  120.